Qualitätssicherung (PDF-Vergleich)

Um zu gewährleisten, dass neue Versionen des Publishers auch exakt dieselben Ergebnisse liefern wie vorhergehende, verfügt der Publisher über eine Funktionalität, mit der man unerwünschte Verhaltensänderungen erkennen kann.

Die Idee ist folgende: ausgehend von einer Layout-Datei und einem überprüften Ergebnis (Referenz-PDF) kann der Publisher kontrollieren, ob mit der aktuellen Version noch immer dasselbe Ergebnis erzielt wird. Dazu erstellt man eine Layoutdatei und Datendatei im XML Format, lässt eine PDF Datei daraus erzeugen und speichert diese unter dem Namen reference.pdf ab. Bei dem Aufruf von sp compare <Verzeichnis> wird nun der Publisher erneut aufgerufen und prüft visuell, Seite für Seite, ob die resultierende Datei mit der vorher angelegten PDF Datei reference.pdf übereinstimmt.

Voraussetzungen für den Vergleich

Der Publisher sucht rekursiv ausgehend von dem angegebenen Verzeichnis nach Verzeichnissen, die eine Datei layout.xml oder eine Datei publisher.cfg enthalten. In diesem Verzeichnis wird dann ein Publisher-Durchlauf gestartet. Die Layoutdatei muss unter dem Namen layout.xml, die Daten-Datei unter dem Namen data.xml zu finden sein, falls das nicht in der (optionalen) Datei publisher.cfg anders konfiguriert ist.

Der PDF-Vergleich benötigt eine Installation der kostenfreien Programmbibliothek ImageMagick, die skriptbasiert Bilder manipulieren und vergleichen kann. ImageMagick gibt es unter anderem für die Betriebssysteme Windows, Mac und Linux.

Vorgehensweise

Ausgehend von einer Layout- und einer Datendatei erzeugt man in gewohnter Weise eine PDF-Datei. Am einfachsten ist es, wenn man sie direkt mit dem Namen reference.pdf erzeugt. Dafür benutzt man die Option --jobname auf der Kommandozeile.

sp --jobname reference

erzeugt die passende PDF-Datei. Mit

sp --jobname reference clean

löscht man die übrigen und nicht weiter benötigten Zwischendateien. Das Verzeichnis sieht nun so aus:

beispiel/
|-- data.xml
|-- layout.xml
|-- reference.pdf
 
0 directories, 3 files

Wird nun sp compare beispiel aufgerufen, sollte es keine Beanstandung geben und als Ausgabe erscheinen:

$ sp compare beispiel/
Total run time: 1.62956s

Falls nun eine zukünftige Version des Publishers eine visuelle Änderung des Layouts hervorrufen würde, ist die Ausgabe z. B. folgende:

$ sp compare beispiel/
/pfad/zum/verzeichnis/beispiel
Comparison failed. Bad pages are: [0]
Max delta is 2162.760009765625
Total run time: 862.898ms

Die Unterschiede sind als PNG Dateien in dem Verzeichnis enthalten:

beispiel/
|-- data.xml
|-- layout.xml
|-- pagediff.png
|-- publisher.pdf
|-- reference.pdf
|-- reference.png
|-- source.png

Die Dateien source.png und reference.png (bzw. bei mehreren Seiten mit einer Kennung für die Seitenzahl) enthalten die aktuelle Version (source.png) und die Referenz (reference.png) als Grafikdatei. Die Datei pagediff.png (auch hier ggf. mit Kennungen für die Seitenzahlen) stellt die Unterschiede zwischen den ersten beiden Dateien hervorgehoben dar. Die Gemeinsamkeiten werden abgeschwächt dargestellt.

Praxis

Mit den Möglichkeiten des PDF-Vergleichs kann man nun eine Sammlung von Beispieldokumenten erstellen, die produktionstypisch sind. Eine Vorgehensweise besteht darin, eine Verzeichnisstruktur zu erstellen, die wie folgt aufgebaut ist:

qa/
|-- beispiel1
|   |-- data.xml
|   |-- layout.xml
|   |-- reference.pdf
|-- beispiel2
|   |-- data.xml
|   |-- layout.xml
|   |-- reference.pdf
|-- beispiel3
    |-- data.xml
    |-- layout.xml
    |-- reference.pdf

Mit dem Aufruf sp compare qa werden alle Unterverzeichnisse durchlaufen und überprüft.